package com.moralesce.gt.concurrency;

import java.util.List;

/**
 * A service that submits tasks for execution using one of possibly several
 * pooled threads.
 * 
 * @author Brandon Grenier
 */
public interface TaskExecutor {

	/**
	 * Executes the given task sometime in the future.
	 * 
	 * <p>
	 * The task may execute in a new thread or in an existing pooled thread.
	 * </p>
	 * 
	 * @param command The command to execute.
	 */
	public void execute(Runnable command);

	/**
	 * Returns the approximate number of threads that are actively executing
	 * tasks.
	 * 
	 * @return The approximate number of threads that are actively executing
	 * tasks.
	 */
	int getActiveCount();

	/**
	 * Returns the approximate total number of tasks that have been scheduled
	 * for execution.
	 * 
	 * <p>
	 * Because the states of tasks and threads may change dynamically during
	 * computation, the returned value is only an approximation, but one that
	 * does not ever decrease across successive calls.
	 * </p>
	 * 
	 * @return The approximate total number of tasks that have been scheduled
	 * for execution
	 */
	long getTaskCount();

	/**
	 * Returns the approximate total number of tasks that have completed
	 * execution.
	 * 
	 * <p>
	 * Because the states of tasks and threads may change dynamically during
	 * computation, the returned value is only an approximation, but one that
	 * does not ever decrease across successive calls.
	 * </p>
	 * 
	 * @return The approximate total number of tasks that have completed
	 * execution
	 */
	long getCompletedTaskCount();

	/**
	 * Initiates an orderly shutdown in which previously submitted tasks are
	 * executed, but no new tasks will be accepted.
	 * 
	 * <p>
	 * Invocation has no additional effect if the service has already been shut
	 * down.
	 * </p>
	 */
	void shutdown();

	/**
	 * Attempts to stop all actively executing tasks, halts the processing of
	 * waiting tasks, and returns a list of the tasks that were awaiting
	 * execution.
	 * 
	 * <p>
	 * This implementation cancels tasks via Thread.interrupt(), so if any tasks
	 * mask or fail to respond to interrupts, they may never terminate.
	 * </p>
	 * 
	 * @return A List<Runnable> of tasks that never commenced execution
	 */
	List<Runnable> shutdownNow();

	/**
	 * Determines if this service has been shut down.
	 * 
	 * @return true if this service has been shut down, false otherwise.
	 */
	boolean isShutdown();

	/**
	 * Determines if this service is in the process of terminating after
	 * shutdown or shutdownNow but has not completely terminated. Returns:
	 * 
	 * @return true if this service is in the process of terminating but not yet
	 * terminated, false otherwise.
	 */
	boolean isTerminating();

	/**
	 * Determines if all tasks have completed following shut down.
	 * 
	 * <p>
	 * Note that isTerminated is never true unless either shutdown or
	 * shutdownNow was called first.
	 * </p>
	 * 
	 * @return true if all tasks have completed following shut down, false
	 * otherwise.
	 */
	boolean isTerminated();

}